Skip to main content

##Availability In order to access the APIs, you should target a site through its URL along with:

http://[site-url]/api/v{number}/{endpoint}

In the previous example, number corresponds to the version of the API and endpoint to the action you are calling.

Language

The official language of the APIs is English: all the objects returned by the API (or sent back to it) contain properties named only in English. The content of the response will correspond to the language provided in the Accept-Language request header. The APIs will fallback to the default language if the Accept-Language request header is missing. The same will happen if the header makes reference to a language that is not available.

Authorization

In order to interact with the APIs, the application will need to be identified through a client_id and a client_secret, using the url http://[site-url]/api/token. You will get a token that must be in the Authorization header of each API call: Authorization: bearer token where token is the token.

The protocol involved is OAuth2.

Below an example of a request to get a token :

POST https://[site-url]/api/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=<your client Id>&client_secret=<your secret>&grant_type=client_credentials

Note: take care to url encode the values contains in the body. If one of the values contains a + not urlencoded, you'll get an error that the says invalid secret for example

The response will contain the access_token :

{
     "access_token": "433fKaLfINnJB46DhWIVFyoVmPzX3h7ZUauAfOaT046KyXqd0qFIkAa3MOAHHYgHKU9tF",
     "token_type": "bearer",
     "expires_in": 1199
}

API usage by topic

Create a job application​

You can create a job application through API via two different endpoints:

  1. POST /api/v1/candidates/{id}/vacancies/{vacancyReference}, where id is the candidate's id and vacancyReference is the reference of the vacancy. The following is a minimal working example for the body of the request:
    {
      "applicationInformation": {
        "publicationMediaId": "_TS_CO_PublicationSupport_Internet"
      }
    }

Cinematic of API calls to create an application on a vacancy:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /api/token

  2. Get a list of all vacancies: GET /api/v1/vacancies

  3. Get the details of a specific vacancy: GET /api/v1/vacancies/{vacancyReference}

  4. Get a list of all the candidates: GET /api/v1/candidates

  5. Get the details of a specific candidate GET /api/v1/candidates/{id}

  6. Apply to selected vacancy (documents can be attached): POST /api/v1/candidates/{id}/vacancies/{vacancyReference}

  7. POST /api/v1/vacancies/{vacancyReference}/applications, where vacancyReference is the reference of the vacancy for which the application is done, and the information of the candidate are given in the body of the request which should be of the following structure (minimal working example):

{
  "candidateInformation": {
    "lastName": "candidateFirstName",
    "firstName": "candidateLastName",
    "email": "email@test.com"
  },
  "applicationInformation": {
    "publicationMediaId": "_TS_CO_PublicationSupport_Internet"
  }
}

Cinematic of API calls to create an application on a vacancy:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /api/token
  2. Get a list of all vacancies: GET /api/v1/vacancies
  3. Get the details of a specific vacancy: GET /api/v1/vacancies/{vacancyReference}
  4. Apply to selected vacancy (documents can be attached): POST /api/v1/vacancies/{vacancyReference}/applications

Referral Case​

The Customer scope allows customers or partners to integrate a referral process in the Talentsoft recruiting solution. By creating an application (as described above) and specifying certain information in the body of the request, a candidate can get referred for a vacancy by an employee. More specifically, the cooptation data must be provided in the block referral inside the block applicationInformation as shown in the example below:

    {
      "applicationInformation": {
        "publicationMediaId": "_TS_CO_PublicationSupport_Internet",
        "referral": {
            "feedback": "feedback text",
            "date": "2022-12-22T00:20:34.869Z",
            "employeeId": "123456"
        }
      }
    }

In the above example, the employeeId is the field id found in the response body of the endpoint GET /api/v1/employees in the data object of the corresponding employee.

Cinematic of API calls to create an application on a vacancy with referral using the candidate endpoint:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /api/token
  2. Get a list of all vacancies: GET /api/v1/vacancies
  3. Get the details of a specific vacancy: GET /api/v1/vacancies/{vacancyReference}
  4. Get a list of all the candidates: GET /api/v1/candidates
  5. Get the details of a specific candidate GET /api/v1/candidates/{id}
  6. Get a list of all the employees: GET /api/v1/employees
  7. Get the details of a specific employee GET /api/v1/employees/{id}
  8. Apply to selected vacancy (documents can be attached): POST /api/v1/candidates/{id}/vacancies/{vacancyReference}

In order to implement the referral process as a customer or partner, we propose the following procedures:

Cinematic of API calls to retrieve the referentials needed for initialization or for updating the libraries when needed:​

  1. Retrieve a token “as an application” (grant_type=client_credentials): POST /api/token
  2. Get all referentials, by category (example for organisations referential): GET /api/v1/referentials/organisations
  3. Get referentials translations using the id of a specific item. Two cases:
    • Get all available translations of referential item: GET /api/v1/referentials/organisations/{id}/translations
    • Get the item's translation in one specific language: GET /api/v1/referentials/organisations/{id}/translations/{lcid}

To retrieve users, vacancies, candidates or employees:​

Use the dedicated endpoints. For example to get a list of all candidates: GET /api/v1/candidates

Note: It is recommended use these endpoints once in order to retrieve the vacancies and the candidates to get the initial lists. To avoid multiple calls you can use webhooks to get notified when there are changes in vacancies and candidates by subscribing to the events vacancy_new, vacancy_update, applicant_status. For more information on the use of webhooks please visit the dedicated section.

When the application is finalized:​

In order to indicate that the referral bonus can be granted to the employee who has made the referral, use the endpoint POST /api/v1/applications/{id}/referralbonus, where id is the application identifier.

Referential Management​

With the Recruiting Customer APIs clients are allowed to manage referentials in order to have more appropriate libraries that better correspond to their needs. Thus, through the corresponding endpoints, one can add an item to a library, modify it or delete it.

The following is the list of the referentials that are currently available for modification via API.

Currentrly Modifiable Referentials
- attachedfiletypecategories
- candidatestatuses
- contracttypes
- currencies
- eeo
- educationlevels
- experiencelevels
- geographicalareas
- jobfamilycategories
- jobtimes
- languages
- languagelevels
- nationalities
- professionalcategories
- recruitingreasons
- salaryranges
- sexes
- skills
- specialities
- titles
- typeofbonuses
- vacancycategories
- vacancystatuses
- radius
- vacancyrequestevents
- vacancyrequeststatus
- vacancyrequestapprovalevents
- vacancyrequestapprovalstatus

Add a new library item​

To add a new referential, for example in the skills library, you can use the endpoint POST api/v1/referentials/skills using a request body of the following structure:

    {
        "label": "newSkillLabel",
        "orderNumber": 0
    }

Modify an existing library item​

Similarly, to modify an already existing library item you can use the endpoint PUT /api/v1/referentials/skills/{id}, where id is the id of the item concerned and using the same body structure as above.

Delete a library item​

Finally, a specific library item can be deleted by using the endpoint DELETE /api/v1/referentials/skills/{id}.

Employees and Users Management​

Creation and modification of employees and users is possible via API.

Employees​

For the creation and the update of an employee, the same endpoint is used: PUT /api/v1/employees/{id}, where id is the employee client code. If an employee with this client code already exists, then this employee gets updated, otherwise a new employee will be created with that client code.

In both cases, the request body should be of the following structure (minimal working example for creation):

{
  "lastName": "employee_LastName",
  "firstName": "employee_FirstName ",
  "email": "employee@email.com",
  "employeeInformation": {
    "associatedOrganisationId": "organizationId"
  },
  "frontOfficeAccount": {
    "communicationLanguage": 1036,
    "login": "employee_Login"
  }
}

Users​

For the creation and the update of a user, the same endpoint is used: PUT /api/v1/users/{login}, where login is the login of the user. If the login already exists then the corresponding user will be updated, otherwise a new user will be created with this login.

In both cases, the request body should be of the following structure (minimal working example for creation):

{
  "userProfile": "userProfile",
  "organisations": [
    "organizationId"
  ],
  "name": "user_LastName",
  "firstName": "user_FirstName",
  "email": "user@email.com"
}

There is also the possibility to delete a user by using the endpoint DELETE /api/v1/users/{login}.

Exports​

Customer scope offers streaming APIs for exporting candidates, vacancies and vacancy requests with the corresponding endpoints:

  • GET /api/exports/v1/candidates
  • GET /api/exports/v1/vacancies
  • GET /api/exports/v1/vacancyrequests

These endpoints return data as streaming and could be identified with these elements :

  • Response Header contains: Content-Type: application/octet-stream
  • Chunked Transfer Encoding protocol (see Wikipedia)
  • Data provided are binary formatted, described below.

Each data block is preceded by a 4-byte header which provides the size of the data block that follows.

A stream containing 2 data blocks is broken down in the followins way:

|------------------Chunk 1-------------------|------------------Chunk 2-------------------|

|------4 Bytes-----|---------c Bytes---------|------4 Bytes-----|---------z Bytes---------|

|Size of next block| Block containing data |Size of next block| block containing data |

| value = c | | value = z | |

Note: the size of blocks in the headers is serialized with the bytes inverted. The value indicating a size of 1 is encoded as follows:

|---Byte---|---Byte---|---Byte---|---Byte---|

| 00000001 | 00000000 | 00000000 | 00000000 |

A block may contain data from one object in the ZIP format.

The ZIP may contain several files, and by convention the JSON data is always placed in a file containing the model in UTF8 JSON format, using the following nomenclature:

  • Vacancy: offerdetail
  • Candidate: candidatedetail
  • Vacancy Request: vacancyRequestDetail

Pagination information is in the header:

- Content-Range: {offset}-{limit}/{total items}

Where offset gives the index starting point for the page from the total returned data (begins at 0), limit is the size of the page and total items refers to the total number of items returned for the request.

Use of Webhooks

The use of webhooks is available for Customer scope which allows you to get notified when there are changes such as new vacancies/applicants or modifications on existing vacancies/applicants. You can subscribe to an event in order to receive notifications when the event is triggered.

By default, the mechanism to call peers to inform them of any change is triggered every 15 minutes but can be modified by the client.

To register to an event you must first retrieve a token “as an application” (grant_type=client_credentials): POST /api/token.

To subscribe to the event you must call the endpoint: POST /api/system/v1/webhooks

In the body of the request you must specify the event you want to subscribe to, a callback URL on which Recruiting may call the subscriber and a ping URL on which Recruiting may call when a ping is requested. For example if you want to get notified when new vacancies are available:

POST /api/system/v1/webhooks
Authorization: Bearer /* Oauth2 token */

{
 "event": "vacancy_new",
 "callbackUrl": "https://example.com/api/talentsoft/v1/events",
 "pingUrl": "https://example.com/api/talentsoft/v1/pingevents" 
}

The response will contain a hookId which can be used to unsubscribe from the event using the endpoint: DELETE /api/system/v1/webhooks/{hookId}

Note: For the complete list of webhook events available for subscription please visit this page.